# Neo4j Knowledge Graph Complete Tutorial

[![Neo4j](https://img.shields.io/badge/Neo4j-5.15.0-blue?logo=neo4j)](https://neo4j.com)
[![Python](https://img.shields.io/badge/Python-3.9+-green?logo=python)](https://python.org)
[![GDS](https://img.shields.io/badge/GDS-2.6-purple)](https://neo4j.com/docs/graph-data-science/)
[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)

> **A comprehensive 100+ page tutorial covering Neo4j from basics to production Graph RAG**

Perfect for hackathons, students, and production applications. All code is executable and follows a logical sequence for teaching.

---

## 📋 Table of Contents

- [Features](#-features)
- [Quick Start](#-quick-start)
- [Project Structure](#-project-structure)
- [Tutorial Sections](#-tutorial-sections)
- [API Documentation](#-api-documentation)
- [Healthcare Data Model](#-healthcare-data-model)
- [Performance Benchmarks](#-performance-benchmarks)
- [Troubleshooting](#-troubleshooting)

---

## ✨ Features

| Category | Features |
|----------|----------|
| **Foundations** | Nodes, Properties, Relationships, CRUD, Advanced Cypher |
| **Indexing** | Range, Text, Fulltext, Vector (HNSW), Spatial |
| **Graph Data Science** | PageRank, Betweenness, Louvain, Node Similarity, Pathfinding |
| **Knowledge Graphs** | Ontology Design, Medical Ontologies (ICD-11, RxNorm, SNOMED CT) |
| **Graph RAG** | Document Chunking, Vector Embeddings, Semantic Search, LLM Integration |
| **Production** | REST API, Transaction Management, Batch Operations, Clustering |

---

## 🚀 Quick Start

### Prerequisites

- Docker & Docker Compose
- Python 3.9+
- 8GB+ RAM recommended

### Step 1: Clone Repository

```bash
git clone https://github.com/yourusername/neo4j-knowledge-graph-tutorial.git
cd neo4j-knowledge-graph-tutorial
```

### Step 2: Start Neo4j

```bash
docker-compose up -d
# Wait ~60 seconds for initialization
docker-compose logs -f neo4j  # Watch for "Started."
```

### Step 3: Setup Python Environment

```bash
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

### Step 4: Configure Environment

```bash
cp .env.example .env
# Edit .env with your settings (default: password123)
```

### Step 5: Load Sample Data

```bash
python src/07_data_loader.py
```

### Step 6: Verify Installation

```bash
python src/01_connection_basics.py
```

### Step 7: Access Neo4j Browser

Open http://localhost:7474

- **Username:** neo4j
- **Password:** password123

---

## 📁 Project Structure

```
neo4j-knowledge-graph-tutorial/
│
├── 📖 COMPLETE_TUTORIAL.md        # 100+ page comprehensive tutorial (5200+ lines)
├── 📖 README.md                   # This file
├── 📦 requirements.txt            # Python dependencies
├── 🐳 docker-compose.yml          # Neo4j Docker configuration
├── ⚙️  .env.example               # Environment template
│
├── src/                           # Source code (numbered for teaching)
│   ├── utils/
│   │   └── connection.py          # Database connection utilities
│   │
│   │── 01_connection_basics.py    # Connection patterns
│   │── 02_nodes_and_properties.py # Node operations
│   │── 03_relationships.py        # Relationship operations
│   │── 04_basic_queries.py        # CRUD operations
│   │── 05_advanced_queries.py     # Complex Cypher patterns
│   │── 06_indexing_and_constraints.py
│   │── 07_data_loader.py          # Bulk data loading
│   │── 08_transaction_management.py
│   │── 09_batch_operations.py
│   │── 10_gds_basics.py           # GDS fundamentals
│   │── 11_centrality_algorithms.py
│   │── 12_community_detection.py
│   │── 13_similarity_algorithms.py
│   │── 15_pathfinding_algorithms.py
│   │── 18_ontology_design.py      # Knowledge graph ontology
│   │── 19_populate_ontology.py
│   │── 20_chunking_strategies.py  # Document chunking for RAG
│   │── 21_vector_embeddings.py    # Embedding generation
│   │── 22_hnsw_indexing.py        # Vector search
│   │── 23_graph_rag_basics.py     # Graph RAG implementation
│   │── 26_large_scale_clustering.py
│   └── 30_api_server.py           # FastAPI REST API
│
├── data/
│   └── sample_healthcare_data.json
│
├── examples/
│   ├── healthcare_kg/
│   └── document_rag/
│
└── tests/
    └── test_connection.py
```

---

## 📚 Tutorial Sections

### Part I: Foundations (Sections 1-10)

| Section | File | Topic |
|---------|------|-------|
| 1 | - | Introduction to Graph Databases |
| 2 | - | Environment Setup |
| 3 | `02_nodes_and_properties.py` | Nodes, Labels, Properties |
| 4 | `03_relationships.py` | Relationships and Patterns |
| 5 | `04_basic_queries.py` | Basic CRUD Operations |
| 6 | `05_advanced_queries.py` | Advanced Cypher Queries |
| 7 | `06_indexing_and_constraints.py` | Indexing and Constraints |
| 8 | `08_transaction_management.py` | Transaction Management |
| 9 | `09_batch_operations.py` | Batch Operations and Import |
| 10 | - | Schema Design Patterns |

### Part II: Graph Data Science (Sections 11-17)

| Section | File | Topic |
|---------|------|-------|
| 11 | `10_gds_basics.py` | GDS Library Fundamentals |
| 12 | `11_centrality_algorithms.py` | Centrality Algorithms |
| 13 | `12_community_detection.py` | Community Detection |
| 14 | `15_pathfinding_algorithms.py` | Pathfinding Algorithms |
| 15 | `13_similarity_algorithms.py` | Similarity Algorithms |
| 16 | - | Link Prediction |
| 17 | - | Graph Embeddings |

### Part III: Knowledge Graphs (Sections 18-25)

| Section | File | Topic |
|---------|------|-------|
| 18 | `18_ontology_design.py` | Ontology Design |
| 19 | `19_populate_ontology.py` | Populating Knowledge Graphs |
| 20 | `20_chunking_strategies.py` | Document Chunking Strategies |
| 21 | `21_vector_embeddings.py` | Vector Embeddings |
| 22 | `22_hnsw_indexing.py` | HNSW Vector Indexing |
| 23 | `23_graph_rag_basics.py` | Graph RAG Implementation |
| 24 | - | Advanced Graph RAG Patterns |
| 25 | - | LLM Integration |

### Part IV: Production Systems (Sections 26-30)

| Section | File | Topic |
|---------|------|-------|
| 26 | `26_large_scale_clustering.py` | Large-Scale Graph Clustering |
| 27 | - | Neo4j Internal Architecture |
| 28 | - | Performance Optimization |
| 29 | - | Enterprise Deployment |
| 30 | `30_api_server.py` | REST API Development |

---

## 🔌 API Documentation

### Start the API Server

```bash
uvicorn src.30_api_server:app --reload --port 8000
```

### Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Health check |
| GET | `/stats` | Database statistics |
| POST | `/nodes` | Create node |
| GET | `/nodes/{label}/{id}` | Get node |
| PUT | `/nodes/{label}/{id}` | Update node |
| DELETE | `/nodes/{label}/{id}` | Delete node |
| POST | `/relationships` | Create relationship |
| POST | `/query` | Execute Cypher |
| POST | `/rag` | Graph RAG query |

### Example Usage

```bash
# Create a patient
curl -X POST http://localhost:8000/nodes \
  -H "Content-Type: application/json" \
  -d '{"label": "Patient", "properties": {"id": "P001", "name": "John Doe"}}'

# Execute Cypher query
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "MATCH (n:Patient) RETURN n LIMIT 10"}'

# Graph RAG query
curl -X POST http://localhost:8000/rag \
  -H "Content-Type: application/json" \
  -d '{"question": "What medications treat diabetes?", "top_k": 5}'
```

### Interactive Documentation

- **Swagger UI:** http://localhost:8000/docs
- **ReDoc:** http://localhost:8000/redoc

---

## 🏥 Healthcare Data Model

```
┌───────────────────────────────────────────────────────────────────┐
│                    HEALTHCARE KNOWLEDGE GRAPH                     │
├───────────────────────────────────────────────────────────────────┤
│                                                                   │
│    ┌──────────┐         DIAGNOSED_WITH         ┌──────────┐      │
│    │ Patient  │───────────────────────────────▶│ Disease  │      │
│    │          │                                │ (ICD-11) │      │
│    └────┬─────┘                                └────┬─────┘      │
│         │                                          │             │
│         │ TAKES                            TREATS  │             │
│         │                                          │             │
│         ▼                                          ▼             │
│    ┌──────────┐                            ┌──────────┐          │
│    │Medication│◀───────────────────────────│Medication│          │
│    │ (RxNorm) │         TREATS             │          │          │
│    └──────────┘                            └──────────┘          │
│                                                                   │
└───────────────────────────────────────────────────────────────────┘
```

### Node Types

| Node | Properties | Ontology |
|------|------------|----------|
| Patient | id, name, dateOfBirth, gender, bloodType, allergies | - |
| Disease | id, name, category, description, severity | ICD-11 |
| Medication | id, name, genericName, drugClass, dosageForms | RxNorm |
| Chunk | id, content, embedding, index | - |
| Document | id, title, source | - |

### Relationship Types

| Relationship | Properties |
|--------------|------------|
| DIAGNOSED_WITH | diagnosedDate, diagnosedBy, status, severity |
| TAKES | prescribedDate, dosage, frequency, status, refills |
| TREATS | effectiveness, firstLine, evidenceLevel |
| INTERACTS_WITH | severity, description, mechanism |
| CONTAINS | - |
| MENTIONS | - |
| NEXT | - |

---

## ⚡ Performance Benchmarks

| Operation | Target | How to Achieve |
|-----------|--------|----------------|
| Indexed lookup | < 1 ms | Range index on property |
| 2-hop traversal | < 5 ms | Warm page cache |
| Vector search (10K) | < 10 ms | HNSW index |
| PageRank (10K nodes) | < 500 ms | GDS projection |
| Bulk insert (1K) | < 100 ms | UNWIND pattern |
| Graph RAG query | < 200 ms | Combined techniques |

### Tips for 5ms Queries

1. **Create indexes** on frequently queried properties
2. **Size page cache** to fit working set in memory
3. **Use parameterized queries** for plan caching
4. **Profile queries** with `PROFILE` prefix
5. **Warm up cache** after restart

---

## 🔧 Troubleshooting

### Connection Refused

```bash
docker-compose ps           # Check status
docker-compose logs neo4j   # View logs
docker-compose restart neo4j
```

### Authentication Failed

```bash
# Recreate with clean data
docker-compose down -v
docker-compose up -d
```

### Out of Memory

Edit `docker-compose.yml`:
```yaml
- NEO4J_dbms_memory_heap_max__size=4G
- NEO4J_dbms_memory_pagecache_size=4G
```

### GDS Not Available

```bash
docker exec neo4j-tutorial ls /plugins
# Should show: graph-data-science-*.jar
```

---

## 📖 Read the Full Tutorial

The complete 100+ page tutorial is in **[COMPLETE_TUTORIAL.md](COMPLETE_TUTORIAL.md)**

It covers:
- Graph database fundamentals
- All Cypher operations
- GDS algorithms with examples
- Building knowledge graphs
- Implementing Graph RAG
- Neo4j internals and performance
- Production deployment

---

## 📄 License

MIT License

---

**Happy Graph Building! 🚀**
